optable-targeting: Enhance Optable Targeting: Non-blocking network calls and granular traffic controls by softcoder594 · Pull Request #2 · Optable/prebid-server-java

softcoder594 · 2026-05-05T15:56:04Z

Type of changes

module update

What's the context?

This update reduces auction latency by initiating the Optable API call at the earliest hook stage (raw-auction-request) and deferring the wait to the per-bidder stage (bidder-request), where the enrichment data is actually injected. It also adds granular controls over which traffic and which bidders receive enrichment.

New Features

Non-Blocking Early Network Call: The API call starts in raw-auction-request and runs in parallel with other auction processing. The result is consumed per-bidder in bidder-request, avoiding pipeline blocking.
Per-Bidder Enrichment Percentage: Configurable sampling rate per bidder (0-100%) to control what fraction of bid requests receive enrichment.
Web vs. App Traffic Toggle: enrich-web / enrich-app flags to select which traffic sources are enriched.

Backwards Compatibility

The processed-auction-request hook is retained as a legacy fallback. If operators have not migrated to the new execution plan, the module behaves as before — enrichment happens synchronously in the processed hook.

New Configuration (recommended)

hooks:
  modules:
    optable-targeting:
      enrichment-percentage: 100
      bidder-enrichment-percentages:
        appnexus: 75
        rubicon: 75
        pubmatic: 100
        criteo: 0
      enrich-web: true
      enrich-app: true

  execution-plan:
    endpoints:
      "/openrtb2/auction":
        stages:
          raw-auction-request:
            groups:
              - timeout: 50
                hook-sequence:
                  - module-code: "optable-targeting"
                    hook-impl-code: "optable-targeting-raw-auction-request-hook"
          bidder-request:
            groups:
              - timeout: 50
                hook-sequence:
                  - module-code: "optable-targeting"
                    hook-impl-code: "optable-targeting-bidder-request-hook"
          auction-response:
            groups:
              - timeout: 10
                hook-sequence:
                  - module-code: "optable-targeting"
                    hook-impl-code: "optable-targeting-auction-response-hook"

Legacy Configuration (to be migrated)

The following execution plan fragment should be removed once migrated to the new configuration above:

          processed-auction-request:
            groups:
              - timeout: 600
                hook-sequence:
                  - module-code: "optable-targeting"
                    hook-impl-code: "optable-targeting-processed-auction-request-hook"

The processed-auction-request hook detects whether the new hooks (raw-auction-request and bidder-request) are present in the execution plan. If both are active, it passes through immediately without blocking the pipeline. If the new hooks are absent, it falls back to the legacy synchronous behavior. This means the legacy fragment can be kept during migration without negating the latency benefit of the new configuration.

Test plan

Unit Tests
Manual Integration Tests

Quality check

Are your changes following our code style guidelines?
Are there any breaking changes in your code? No
Does your test coverage exceed 90%?
Are there any erroneous console logs, debuggers or leftover code in your changes? No

ericst-amand-optable · 2026-06-03T19:54:25Z

I suggest those validation functions are placed in the same package as OptableTargetingProperties. It will encourage reusability and reduce imports.

@softcoder594

I would rather keep the Validator class outside the models package.

ericst-amand-optable

Looks good overall. Submitted some small comments/refactor. I did not try to run the server, nor the tests, so this is pure code review for what it is.

…aching

return early from the hook if (hasRawAuctionRequestHook && hasBidderRequestHook) - the new mode

random is 0-99, percentage is 0-100. enrich when random < (strictly less than) percentage. so if we specify percentage 0 we never enrich, if we specify percentage 100 we always enrich.

eugenedorfman-optable

On the raw + bidder execution plan at enrichment-percentage: 100, the early Targeting API call is fired on every auction and nothing reads the result: OptableTargetingProcessedAuctionRequestHook returns early whenever both hooks are in the plan, and OptableBidderRequestHook drops every bidder before it touches the future. The cost is a real HTTP request plus a cache write per auction, no bid request enriched, nothing in the analytics tags, and a failed future with no handler attached, so failures are invisible.

This only bites if you deploy that plan at 100% with no bidder-enrichment-percentages. Cause and fix inline.

eugenedorfman-optable

isPerBidderEnrichmentEnabled() makes enrichment-percentage: 100 behave as though per-bidder enrichment were switched off, which is what leaves the early Targeting API call without a consumer on the raw + bidder plan. 100% should be just another sampling rate, no different from 50%. Suggestion inline.

eugenedorfman-optable · 2026-07-30T21:30:48Z

+        final OptableTargetingProperties properties = moduleContext.getOptableTargetingProperties();
+        if (!properties.isPerBidderEnrichmentEnabled()) {
+            return noAction(moduleContext, null);
+        }
+


This guard is the special case that orphans the early Targeting API call, as described in the comment above.

biddersToEnrich already describes exactly what to enrich at any percentage: BidderEnrichmentSampler.sample excludes a bidder when its percentage is 0 and includes it when the percentage is 100, resolving per-bidder overrides before falling back to the default. The check on the next lines is therefore sufficient and uniform. This extra gate adds a second, inconsistent notion of "is per-bidder enrichment on", and it reads backwards: enrichment-percentage: 100 is the setting that asks for the most enrichment, and it is the one value that makes isPerBidderEnrichmentEnabled() false.

The effect on the raw + bidder plan is that at 100% every bidder is sampled in, the raw hook fires the call, and then every bidder is dropped here without the future ever being read.

Deleting the gate makes the behaviour uniform across percentages and gives the call its consumer back:

Suggested change

final OptableTargetingProperties properties = moduleContext.getOptableTargetingProperties();

if (!properties.isPerBidderEnrichmentEnabled()) {

return noAction(moduleContext, null);

}

final OptableTargetingProperties properties = moduleContext.getOptableTargetingProperties();

isPerBidderEnrichmentEnabled() in OptableTargetingProperties has no other caller, so it can go too.

Two things to sanity check before taking it. First, at 100% on the raw + bidder plan this turns bid request enrichment on where it is currently off, which is presumably the intent but is a live behaviour change. Second, if the gate was there to keep some other execution plan on the old whole-request path, that is worth stating, though OptableTargetingProcessedAuctionRequestHook only defers to the bidder hook when both hooks are in the plan, so I could not find such a path.

Worth a test either way: raw + bidder plan at enrichment-percentage: 100 should assert that every sampled bidder is enriched.

…ntage property is specified and it's value is 100%

eugenedorfman-optable

The guard removal is right: isPerBidderEnrichmentEnabled() and its caller are both gone, nothing else referenced it, and the early Targeting API call now has a consumer at enrichment-percentage: 100. 147 tests pass.

The @JsonProperty("enrichment-percentage") in the same commit is a separate and real fix: per-account overrides of that key were being silently dropped. Two sibling fields still have it, inline below.

eugenedorfman-optable · 2026-07-31T12:17:13Z

+    Boolean enrichWeb = true;
+
+    Boolean enrichApp = true;
 }


enrichWeb and enrichApp have the same binding bug that @JsonProperty("enrichment-percentage") just fixed on the field above.

ConfigResolver.resolve merges the per-account node over mapper.valueToTree(globalProperties) and deserializes the result with the prebid mapper, which sets PropertyNamingStrategies.SNAKE_CASE. Unannotated multi-word fields therefore bind to enrich_web and enrich_app, while README.md documents enrich-web and enrich-app as the account config keys (lines 105-106 for JSON, 128-129 for YAML). An account key spelled the documented way is an unknown property, gets dropped, and the account silently keeps the global value.

Global YAML is unaffected either way, since Spring relaxed binding handles kebab-case. This only bites per-account overrides, which is exactly why it goes unnoticed.

Suggested change

Boolean enrichWeb = true;

Boolean enrichApp = true;

}

@JsonProperty("enrich-web")

Boolean enrichWeb = true;

@JsonProperty("enrich-app")

Boolean enrichApp = true;

}

Verified: module suite stays green with this applied. Worth a ConfigResolver test covering per-account overrides of all four documented keys, since none of them has one today.

The account config node is deserialized with the prebid mapper, which uses SNAKE_CASE, so the unannotated fields bound to enrich_web and enrich_app while the documented account keys are enrich-web and enrich-app. Per-account overrides of both were silently dropped and the global value kept.

softcoder594 changed the title ~~optable-targeting: implement Non-Blocking Early Network Call~~ optable-targeting: Enhance Optable Targeting: Non-blocking network calls and granular traffic controls May 25, 2026

justadreamer mentioned this pull request Jun 2, 2026

Optable targeting doc Optable/prebid.github.io#5

Open

2 tasks

ericst-amand-optable reviewed Jun 2, 2026

View reviewed changes

Comment thread sample/configs/prebid-config-with-optable-legacy.yaml Outdated